SSO Authentication

Flow

Access token flow diagram

When the application starts, authentication service provider identification is checked.
The local storage of browser is checked to have a Refresh Token for the current user.
If Refresh Token exists, Silent Token Update is performed to obtain a new Access Token.
If Silent Token Update fails for any reason, the user will be logged out and redirected to a Login page.
Application back-end uses auth provider to validate access tokens.

Basic Configuration

This is the example of a common configuration for SSO authentication. Further in text, you can find examples of configurations for selected auth service providers.

# example of SSO common configuration
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: <issuer uri>
security:
  oauth2:
    provider:
      providerType: SSO
      name: <name>
      clientId: <client id>
      audience: <audience>
	  jwksUrl: <jwks url>
      configUrl: <config url>
      logoutUrl: <logout url>
      usernameClaim: <username claim>
	  permissionsClaim: <permissions path claim>
      validateIssuer: <true|false>
	  userInfo:
		enable: <true|false>
		userInfoUrl: <user info url>
		usernameKey: <list of username keys>

Parameter	Description
issuer-uri	URI of the auth service provider.
name	Name of the auth service provider.
clientId	Each connected application is given a personal ClientId from the provider.
audience	Unique identifier of the audience for an issued token, identified within a JSON Web Token as the `audclaim`. Each connected back-end (API) is given a personal `audience` from the auth provider. `audience` is always associated with a specific auth provider and may be optional with some providers.
jwksUrl	URL of the authorization server's JWK Set document. The referenced document contains the signing key(s) the client uses to validate signatures from the authentication server.
configUrl	Standard service provider endpoint.
logoutUrl	Standard service provider logout URL.
usernameClaim	Username claim in token.
permissionsClaim	Authorities claim in token.
validateIssuer	Set `true` to enable validation of auth provider URL in token against `issuer-uri`.
userInfo.enable	Set `true` to enable user info URL by auth service provider.
userInfo.userInfoUrl	URL with information about the user provided by the auth service provider.
userInfo.usernameKey	Default usernames claims in token from auth service provider.

User Configuration

Some SSO auth providers allow defining permissions for users and passing them in permissionsClaim.

info

Refer to Configuration to learn how to add or override the default configuration.

# example of configuring user roles via permissions claim from auth provider
security:
  oauth2:
    provider:
      providerType: SSO
      name: <name>
      clientId: <client id>
      audience: <audience>
	  jwksUrl: <jwks url>
      configUrl: <config url>
      logoutUrl: <logout url>
      usernameClaim: <username claim>
	  permissionsClaim: <permissions path claim>

If your SSO auth provider does not support this, you can define permissions for users in application.yaml config in section users or in a JSON file.

# example of how to define permissions for users for SSO authentication

security:
  oauth2:
    users:
      - username: <username>
        authorities: [TB_ALLOW_READ, TB_ALLOW_WRITE]
      - username: <username>
        authorities: [TB_ALLOW_READ]
...

Supported permissions:

TB_ALLOW_READ - user can select, view, get data stored in TimeBase streams.
TB_ALLOW_WRITE - user can write, modify, delete data stored in TimeBase streams.
GRAFANA - permission allowing Grafana plugin to query data from TimeBase.

You can combine permissions claim from auth provider and custom configurations in one config:

# example of a combination of permissionsClame and custom user configuration
security:
  oauth2:
    users:
      - username: <username>
        authorities: [TB_ALLOW_READ, TB_ALLOW_WRITE]
      - username: <username>
        authorities: [TB_ALLOW_READ]
    provider:
      providerType: SSO
      name: <name>
      clientId: <client id>
      audience: <audience>
	  jwksUrl: <jwks url>
      configUrl: <config url>
      logoutUrl: <logout url>
      usernameClaim: <username claim>
	  permissionsClaim: <permissions path claim>

Configuration Examples for Selected Auth Providers

ORY Hydra

To enable SSO with ORY Hydra, add the following blocks to your application.yaml configuration file.

# example of configuration for ORY Hydra
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: <service provider uri>

security:
  oauth2:
    provider:
      providerType: SSO
      name: hydra
      clientId: <client_id>
      validateIssuer: false
      userInfo:
        enable: true

Amazon Cognito

To enable SSO with Amazon Cognito, add the following blocks to your application.yaml configuration file.

# example of configuration for Amazon Cognito
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: <service provider uri>

security:
  oauth2:
    provider:
      providerType: SSO
      name: cognito
      clientId: <client_id>
      audience: <audience>
      configUrl: <service provider config url>
      logoutUrl: <service provider logout url>
      usernameClaim: username
      validateIssuer: true

Keycloak

To enable SSO with Keycloak, add the following blocks to your application.yaml configuration file.

# example of configuration for Keycloak
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: <service provider uri>

security:
  oauth2:
    provider:
      provider-type: SSO
      name: keycloak
      clientId: <client_id>
      usernameClaim: preferred_username
      validateIssuer: false
      validateClientId: true

Auth0

To enable SSO with Auth0, add the following blocks to your application.yaml configuration file.

# example of configuration for Auth0
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: <service provider uri>

security:
  oauth2:
    provider:
      providerType: SSO
      name: auth0
      clientId: <client_id>
      audience: <audience url>
      configUrl: <configuration url>
      logoutUrl: <logout url>

Azure AD (Entra ID)

To enable SSO with Azure AD:

Configure Azure AD (Entra ID) application.
Add the following blocks to your application.yaml configuration file.

# example of configuration for Auth0
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: <azure ad issuer uri> # for example, "https://login.microsoftonline.com/11111111-1111-1111-1111-1111111111111/v2.0"

security:
  oauth2:
    provider:
      providerType: SSO
      name: azure
      clientId: <SPA Application (client) ID>     # from Overview page of p.4.4, ex. 22222222-2222-2222-2222-222222222222
      validateIssuer: true                        # `true` for tokens with version 2 (configured in p 4.5). Set `false` for v1 tokens
      audience: <Service Application ID>          # application ID created in p.3. (skip this field for v1 tokens)l
      usernameClaim: preferred_username 
      scopes:
        - openid
        - profile
        - offline_access
        - <API Permission>                        # from p. 4.3 of Azure AD configuration, ex. api://timebase/webapp

User Access Control with TimeBase Permissions

Web Admin offers the capability to configure User Access Control (UAC) with permissions derived from the TimeBase server. Each user gets a unique connection to the TimeBase server and can only work with the streams they have permissions for.

Additionally, a "master connection" to TimeBase is created for executing system-level tasks such as processing views, metrics, etc.

Configuration

To configure user access control with permissions from TimeBase:

Configure TimeBase UAC with OAuth2 for a given authentication provider.
Using the examples above, configure WebAdmin SSO UAC for the same authentication provider and add users.
In the Web Admin's application.yaml file, configure authentication for the master connection to TimeBase:

# example of TimeBase Master connection configuration for Azure AD:
timebase:
  oauth2-client:
    url: https://login.microsoftonline.com/b41b72d0-4e9f-4c26-8a69-f949f367c91d/oauth2/v2.0/token
    client-id: 4d69eb9b-e7c3-4bf3-abc3-5c3ad64cb6fc
    client-secret: UlRzOFF+cXo0SW9pdlJXTU5TdVZBWEZ2OWtZTDhXZ0NDUExlMGFTMQ==
    scope: "api%3A%2F%2Ffcf8a41f-bf18-4229-8a2e-ec84d94df340%2F.default"

In the same file, enable UAC with TimeBase permissions:

timebase:
  enable-uac: true              # Enable TimeBase provided UAC

You can also configure the Web Admin to create a separate TimeBase connection for separate IPs:

timebase:
  uac:
    connection-per-ip: false    # Enable this 

Configuration Example for Azure AD

To configure user access control with TimeBase permissions for Azure AD:

In the uac-oauth-security.xml file, configure TimeBase UAC by adding the users and client id taken from the Web Admin's master connection:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<config xmlns="http://xml.deltixlab.com/internal/quantserver/3.0">
    <users>
        <!-- WebAdmin master connection user (client id) -->
        <user id="4d69eb9b-1111-1111-1111-5c3ad64cb6fd">
        </user>
        
        <!-- Users -->
        <user id="User@mail.com">
        </user>
    </users>
    <groups>
        <group id="Administrators">
            <!-- Add WebAdmin master connection user to Administrators group -->
            <principal>4d69eb9b-1111-1111-1111-5c3ad64cb6fd</principal>
        </group>
        <group id="Users">
            <principal>User@mail.com</principal>
        </group>
    </groups>
  <oauthSettings>
    <jwksUrl>https://login.microsoftonline.com/b41b72d0-1111-1111-1111-f949f367c91d/discovery/v2.0/keys</jwksUrl>
    <issuer>https://login.microsoftonline.com/b41b72d0-1111-1111-1111-f949f367c91d/v2.0</issuer>
        <!-- Same client id is used for WebAdmin master connection and users login -->
    <clientId>4d69eb9b-1111-1111-1111-5c3ad64cb6fd</clientId>
        <clientIdClaim>azp</clientIdClaim>
  </oauthSettings>
</config>

In application.yaml, configure the Web Admin by filling the issuer-uri, security, and timebase branches:

...
# Add issuer
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: "https://login.microsoftonline.com/b41b72d0-1111-1111-1111-f949f367c91d/v2.0"
...
timebase:
  url: dxtick://localhost:8011
  enable-uac: true    # Enable TimeBase provided UAC
  # Configure master connection
  oauth2-client:
    url: https://login.microsoftonline.com/b41b72d0-1111-1111-1111-f949f367c91d/oauth2/v2.0/token
    client-id: 4d69eb9b-1111-1111-1111-5c3ad64cb6fd
    client-secret: <client secret>
    scope: "api%3A%2F%2Ffcf8a41f-1111-1111-1111-ec84d94df341%2F.default"
...
# Configure AzureAD SSO
security:
  oauth2:
    provider:
      providerType: SSO
      name: azure
      clientId: 4d69eb9b-1111-1111-1111-5c3ad64cb6fd
      validateIssuer: false
      usernameClaim: preferred_username
      scopes:
        - openid
        - profile
        - api://fcf8a41f-1111-1111-1111-ec84d94df341/app
    users:
      - username: User@mail.com
        authorities: [TB_ALLOW_READ, TB_ALLOW_WRITE]
...

Flow​

Basic Configuration​

User Configuration​

Configuration Examples for Selected Auth Providers​

ORY Hydra​

Amazon Cognito​

Keycloak​

Auth0​

Azure AD (Entra ID)​

User Access Control with TimeBase Permissions​

Configuration​

Configuration Example for Azure AD​